package cn.iocoder.boot.springai001.service;

import cn.iocoder.boot.springai001.entity.ChatSession;
import org.springframework.ai.chat.messages.Message;

import java.util.List;
import java.util.Map;
import java.util.Optional;

/**
 * 会话管理服务接口
 * <p>
 * 定义会话管理的核心方法
 * <p>
 * 实现类：
 * - SessionService: 内存实现（session.storage.type=memory）
 * - SessionServiceJpa: 数据库实现（session.storage.type=database）
 */
public interface ISessionService {

    /**
     * 创建新会话
     */
    ChatSession createSession(String userId, String sessionName, String sessionType);

    /**
     * 根据 sessionId 获取会话
     */
    Optional<ChatSession> getSession(String sessionId);

    /**
     * 根据 userId 获取所有会话
     */
    List<ChatSession> getUserSessions(String userId);

    /**
     * 根据 sessionType 获取会话
     */
    List<ChatSession> getSessionsByType(String userId, String sessionType);

    /**
     * 更新会话最后活跃时间
     */
    void updateLastActive(String sessionId);

    /**
     * 获取会话的消息数量
     */
    int getMessageCount(String sessionId);

    /**
     * 获取会话的聊天记录
     */
    List<Message> getSessionMessages(String sessionId);

    /**
     * 清空会话历史
     */
    void clearSessionHistory(String sessionId);

    /**
     * 删除会话
     */
    boolean deleteSession(String userId, String sessionId);

    /**
     * 置顶会话
     */
    void pinSession(String sessionId, boolean pinned);

    /**
     * 搜索会话
     */
    List<ChatSession> searchSessions(String userId, String keyword);

    /**
     * 获取活跃会话
     */
    List<ChatSession> getRecentActiveSessions(String userId, int limit);

    /**
     * 统计信息
     */
    Map<String, Object> getUserStatistics(String userId);

    /**
     * 根据 sessionId 获取或创建会话
     * <p>
     * 如果会话已存在，返回现有会话并更新最后活跃时间
     * 如果会话不存在，自动创建一个新会话
     *
     * @param sessionId 会话标识
     * @param userId         用户ID（默认为 sessionId，可自定义）
     * @return 会话对象
     */
    ChatSession getOrCreateSession(String sessionId, String userId);
}

